\section{fprintf --- Formatted output to a file}
\label{fn:fprintf}
\index{fprintf()}
\index{formatted output to a file}
\index{strings!output}
\index{scalars!output}
\begin{rail}
FilePrint : 'fprintf' '(' String ',' String ( ( ',' Variable ) * ) ')' ;
\end{rail}

The \verb+fprintf+ function is intended for writing formatted output
to a file. It is similar to the C language function of the same name,
though some features are limited or not available, since \RLaB\
doesn't have all the data types of C.

The first argument is a string which specifies which file the
formatted string is to be written to. If this argument starts with
\verb+|+, then the rest of the argument is taken as a process which
should be invoked, and the formatted output string is sent to that
process.

The second string argument is the format string.  It consists of the
text to be written out, and possibly some conversion specifications.
A conversion specification is a sequence of commands that determine
how the remainder of the arguments are to be displayed.  The left most
conversion specifier is matched to the third argument, the next
specifier to the fourth argument, and so on.  Each argument has to be
matched to a conversion specification.  When the format string is
being scanned, the argument that matches the the specifier that the
scanner is up to is called the {\em current argument}.

Conversion specifications always begin with a \verb+%+ sign.  The next
thing that can occur are the flags:
\begin{description}
\item[--] causing the conversion to be left-justified, instead
of the default right-justified.
\item[+] causing a sign to always be prepended to the
conversion, instead of the default of only prepending minus signs.
\item[\#] which causes the format to be of an alternate form.
This only has meaning for \verb+e+, \verb+E+, \verb+f+, \verb+g+ and
\verb+G+ formats, where is causes a decimal point to be used always.
It also prevents suppression of trailing zeros for \verb+g+ and
\verb+G+ options.
\item[0 (zero)] which causes padding by leading zeros, instead
of the default space padding.  This is overridden by both \verb+-+ and
specifying a precision.
\item[{\it space}] which causes a space to be prepended if no sign is
present.  This is overridden by the \verb|+| flag.
\end{description}

Following any flags, a minimum field width may be specified.  This is
either a integer constant, or a \verb+*+ character. If it is a
constant, this is the minimum width.  If it is a \verb+*+, then the
current argument (which must be a scalar) is used to specify the
minimum width.  If there is an optional width, then there may also be
an option precision.  This is specified in the same way as the width,
using either and integer constant, or a \verb+*+ to signify that the
current argument is to be used.

The next thing that can occur is an optional \verb+h+ or \verb+l+
(ell) modifier.  This changes the behavior of the subsequent \verb+i+
and \verb+u+ conversion specifiers.  It is legal, but has no effect,
with the \verb+d+ specifier.  It is illegal with all other specifiers.

The final thing that must occur is a character specifying the way in
which the current variable is to be displayed.  The valid characters
are
\begin{description}
\item[c] causes the argument to be converted to an unsigned
character format.
\item[d] which causes the output to be displayed as a decimal
string of the form {\it [-]dddd}.  The precision specifies the minimum
number of digits to appear, with a default of one.
\item[e] causes the output to be displayed in scientific
notation of the form {\it [-]d.ddd{\verb+e+}$\pm$dd}, where {\it d} is
any digit.  There is always one non-zero digit before the decimal
place if the argument is non-zero.  The precision specification sets
how many digits are present after the decimal place, with a default of
six.
\item[E] is the same as \verb+e+, except that a upper case
letter \verb+E+ is used to seperate the mantissa and exponent instead
of a lower case \verb+e+.
\item[f] causes the output to be displayed as a decimal string
of the form {\it ddd.ddd}.  the precision specifies how many digits
should appear after the decimal place, with a default of six.
\item[g] is the same as \verb+e+ is the exponent would be less
than -4, or greater than the precision.  Otherwise, it is the same as
\verb+f+.
\item[G] is the same as \verb+E+ is the exponent would be less
than -4, or greater than the precision.  Otherwise, it is the same as
\verb+f+.
\item[i] is the same as \verb+d+, except that the \verb+l+ flag
may be used.
\item[s] may be used to display strings.  If the argument is a
scalar, then this is the same as \verb+f+.
\item[u] displays the argument as an unsigned integer value.
The precision specifies the minimum number of digits to be displayed,
with a default value of one.
\end{description}

The number of arguments must match the number of conversion
specifications, including those required for width and precision
specifications. 

\verb+fprintf+ cannot print out whole matrices or lists.  \verb+write+
knows how to deal with entire data objects.


\paragraph{Example}
\index{example of fprintf()}
\index{fprintf()!example}
\begin{verbatim}
Dummy Example
\end{verbatim}

See also: Page~\pageref{fn:printf} \verb+printf()+,
Page~\pageref{fn:read} \verb+read()+,
Page~\pageref{fn:sprintf} \verb+sprintf()+,
Page~\pageref{fn:write} \verb+write()+.

\newpage






